
AMPlayRCG
~~~~~~~~~

It stands for AMPlay Remote Control Gateway.

This is part of a remote control system for AMPlay. Previously, it was
just called 'AMPlayRC', but in v2, I've changed the name to
'AMPlayRCG', to emphasise the fact that this is really a gateway to
allow the AMPlay API to be accessed from a machine other than the one
where AMPlay is running.

It allows you to run AMPlay on one machine (MachineA), but view its
status and control it from a different machine (MachineB).



Overview
~~~~~~~~

AMPlayRCG does not in itself speak any form of network protocol, but
simply deals with input and output files. Therefore you must already
have some form of network filesystem - the details of that filesystem
are entirely up to you.

MachineA must be a RISC OS system meeting the requirements for running
AMPlay. On MachineA, you run AMPlay and AMPlayRCG.

MachineB can be pretty much anything, as long as it is able to read
from and write to files on a network location that is either on
MachineA, or can also be accessed from MachineA. On MachineB, you run
an AMPlay remote control client of some form (see later section on
clients).

e.g. MachineB might be another RISC OS system, with a ShareFS network
connection to MachineA. It might be a windows PC, to which MachineA has
a LanMan98 connection. Or, MachineA might be running Samba. It doesn't
matter.

Although any network filesystem could be used, I recommend that
MachineA be a server of some kind, whether it be Samba, or ShareFS to
share its disks, or whatever. The reason for this is that AMPlayRCG
will be checking for the existence of its input flag file fairly
frequently, and if its input file is accessed over the network (from
MachineA's viewpoint), then network traffic will result from this
process.

However, if MachineA is a server, and MachineB is using the network
filesystem to access MachineA's local disks, then AMPlayRCC's checks
are to the local hard disk, so no network traffic results except from
actual commands and replies between the machines.

As an example - the setup I use at work consists of MachineA (RiscPC),
running Samba, with the local hard disk as a samba share. MachineB is a
windows PC with its P: drive mapped to the samba share. I have a
symbolic link there which points to the root of the RamDisc. AMPlayRCG
checks for its input file (and writes its output file) in the root of
the RamDisc. This means that AMPlayRCC's activity is not only not
causing network traffic, it doesn't cause any hard disk activity either.

As far as the Windows PC is concerned, it's writing to P:\AMFlags\input.
txt, and has no idea that it's really in a Ramdisc.

In theory, systems such as FTP could be used to send and receive the
files, but this is not a recommended method.



Mechanism
~~~~~~~~~

The client (see later) writes commands to the 'input file'. Once
complete, it creates the 'input flag file', and then waits for the
existence of the 'output flag file'.

AMPlayRCG wait for the existence of the 'input flag file'. Once this
exists, it reads the 'input file'. Once it has read the lines from the
input file both the input file and the input flag file are deleted. The
input file contains commands which tell AMPlayRCG to make AMPlay do
particular things or supply particular information. AMPlayRCG processes
these commands, writing to the 'output file' as it does so. Once it is
complete, it creates the 'output flag file'.

When the output flag file exists, the client should read the output
file, and once done, should delete the output file and the output flag
file.

'input' and 'output' are in quotes because they are from AMPlayRCG's
viewpoint - the client program writes to the input file, and reads from
the output.

The flag files exist to indicate that the files they refer to are ready
to be read. This is to avoid file locking issues (remember that the
client end is on a different machine to AMPlayRCG).

AMPlayRCG also deletes any existing output files (and flags) on startup.

See also the section on sleeping.



Configuration
~~~~~~~~~~~~~

AMPlayRCG contains a file called Choices. This contains the following
settings;

checkinterval=100
inputfile=Input/txt
inputflag=InFlag/txt
outputfile=Output/txt
outputflag=OutFlag/txt
wakeflag=WakeFlag/txt

These should be editted to point the various files to the location you
want them to be processed in. The 'checkinterval' variable is the
number of centiseconds between checks as to whether the input flag file
exists.



File Formats:
~~~~~~~~~~~~~

The input and output flag files only need to be created as needed.
Their contents are not read.

The input file should be formatted as follows;

Lines starting with # are comments
Blank lines are ignored.
Other lines must be of the form;

verb#command#parameter1#parameter2

Depending on the verb used, the commands available will vary. Depending
on the command used, the parameters may be optional, and may vary in
number. In some cases a command may require a parameter1, and a
parameter3, but not a parameter2. This would be done by passing
parameter2 as 0;

verb#command#parameter1#0#parameter3

Verb must be one of the following;

cmd
req
rcg

The input file may contain up to 32 non-commented lines (anything after
that won't be processed).


Cmd:

This verb indicates that you wish AMPlayRCG to send a command to
AMPlay. The verb is followed by the command string (up to 3
characters), then by any parameters that command requires (which will
be assumed to be integers if the string you pass contains only numbers,
or a string otherwise). e.g;

cmd#pau#tog

This would tell AMPlayRCG to send a command to AMPlay to toggle the
pause status.

Req:

This verb indicates that you wish AMPlayRCG to send a request for
information to AMPlay. As with commands, it is followed by the request
string (up to three characters), and any parameters that request
requires.. e.g.;

req#mac#cur#0#Trackname: %tn

This would tell AMPlayRCG to ask AMPlay to expand the macros in the
string 'Trackname: %tn', relative to the currently playing track. The
string to be expanded may contain spaces, does not require quotes, but
may not contain the '#' character.

The req and cmd verbs allow full access to all the commands and
requests listed in the AMPlayAPI. For a complete list of the available
commands and requests, refer to the AMPlay source documentation, which
has a section on the AMPlay API. AMPlayRCG acts as a passthrough for
API requests, so these are AMPlay details, not something coded into
AMPlayRCG.

RCG:

This is a verb for actions specific to AMPlayRCG, that do not involve
sending messages that form part of the AMPlay API. There are three
possible commands that follow it;

rcg#ver
rcg#run
rcg#sleep

The first of these returns version information for AMPlayRCG. The
second one runs AMPlay, and can be used to start AMPlay on the remote
system if it isn't running, or if you've just quit it using the
cmd#die#nrm command.

The sleep command tells AMPlayRCG to stop processing commands. See the
section on sleeping.


Output file format:

Each line in the input file (that isn't blank, or a comment) will
generate one or more lines in the output file.

Each line will generate;

- A Success/Fail line which will be formatted;

verb#cmd: Succeeded.
or
verb#cmd: Error:[error code]:[error message text]

- Further lines if needed;

If the input line was a command to AMPlay, then there are unlikely to
be any further details. It will either succeed or fail, and that's all
you'll get.

However, for requests, the whole purpose is to return information, so
the information you asked for will follow.

A request may return several separate items of information. These will
be returned on subsequent lines in the output. If the returned
information is an integer it will be written as a string into the
output. The information is returned in the order it occurs in AMPlay's
reply to AMPlayRCG. Again, refer to the API documentation.



Waking and Sleeping
~~~~~~~~~~~~~~~~~~~

AMPlayRCG can be sent into a sleep state by;

- Sending rcg#sleep in an input file.
- Clicking Select on the icon bar icon.
- Using the menu item on the icon bar menu.

Once asleep, AMPlayRCG will not process any more commands, and will not
look for the input or input flag files. If sent to sleep by an input
file, any commands in that file which follow the rcg#sleep command will
generate the 'AMPlayRCG is asleep' error.

It will be woken by;

- The wakeflag file existing (see choices).
- Another select click on the icon bar icon
- Using the menu item again.

The iconbar icon indicates the current state - if the remote control is
faded, but the AMPlay logo is solid, then AMPlayRCG is asleep.

Incidentally, if both the remote and the AMPlay logo are faded, then
either AMPlay is not running, or AMPlayRCG is not happy with the
version of it.



Error Codes and Messages
~~~~~~~~~~~~~~~~~~~~~~~~

If AMPlayRCG passes the command/request to AMPlay and AMPlay returns an
error, then those are the same errors and codes that are documented in
the AMPlayAPI documentation.

If the error occurs locally within AMPlayRCG, then the errors and codes
are;

Code:    Error:

64  Unrecognised verb
65  Unrecognised command for verb
66  AMPlay not running.
67  AMPlay not found.
68  AMPlayRCG is asleep.


The 'AMPlay not running' message strictly speaking means that there is
no running application that responds to the v2.00 AMPlay API. i.e.
you'll see this if AMPlay is 1.5x.

The not found error occurs if <AMPlay$Dir>.!Run does not exist, and the
RCG#run command has been sent.

The asleep error occurs for any commands which follow an rcg#sleep
command in the input file. Once asleep, AMPlayRCG does not look for
more input files until it is woken up.



Compatibility
~~~~~~~~~~~~~

Clients of the old AMPlayRC 1.52 will not be compatible with 2.00 and
later. This is because although the mechanism of passing input and
receiving output is the same, the contents of the input file are
completely different. 1.52 had its own commands which it mapped on to
API calls. 2.00 just reformats input into an API call- it has no lookup
table.

AMPlayRCG is also not compatible with versions of AMPlay prior to 2.00.
This because the API is not compatible between 1.5x and 2.x versions of
AMPlay.

AMPlayRCG is not limited to the API as spoken by AMPlay 2.00. Because
it acts as a pass through for the command/request and its parameters,
it will continue to work with extensions to the API. e.g. if AMPlay
2.10 comes out, with extensions to its API, then once the client is
updated to know about those extensions, it can use them via AMPlayRCG,
even if AMPlayRCG has not been updated.



Clients
~~~~~~~

Currently there is only one rudimentary client supplied with AMPlayRCG.
It's a batch file that I use on my work PC for controlling AMPlay.

See the readme supplied with it for details on getting it working.


Future clients:
~~~~~~~~~~~~~~~

Once work on AMPlay 2.00 is complete, I do intend to do;

- !AMPlayRCC. A proper RISC OS client for AMPlayRCG, which would allow
  AMPlay on one RISC OS machine to be controlled from another RISC OS
  machine.

- AMPlayRCC.exe A windows client, probably written in Delphi.

Both of these will be proper GUI apps, rather than scripts.



Multiple clients:
~~~~~~~~~~~~~~~~~

There is nothing stopping you from having multiple clients talking to
the same copy of AMPlayRCG. However, it isn't recommended because there
are potential file locking issues (multiple clients writing to the same
input file simultaneously), and there is no way to indicate which
client should receive the output. For single commands, it should work,
but for clients that poll frequently (as the batch file does, once a
second), it's a bad idea.

I may add some facility for this - probably multiple directory slots,
each of which could have its own input and output files and flags.
However, this isn't high on my own requirements, so if you'd find this
useful, let me know and I'll bump it up the to-do list.

________________________________________________________________________


Version History:
~~~~~~~~~~~~~~~~

2.00 First version. (Version number to match the other AMPlay v2
components)

2.00a Minor update. Fixed the !Run file to load ABCLib correctly if
it wasn't already

________________________________________________________________________
Copyright  2005 Mike Sandells, mike@mikejs.com
Last Modified: 31.10.2005
